/**********
This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the
Free Software Foundation; either version 2.1 of the License, or (at your
option) any later version. (See <http://www.gnu.org/copyleft/lesser.html>.)

This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
more details.

You should have received a copy of the GNU Lesser General Public License
along with this library; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
**********/
// Copyright (c) 1996-2013 Live Networks, Inc.  All rights reserved.
// Basic Usage Environment: for a simple, non-scripted, console application
// C++ header

#ifndef _BASIC_USAGE_ENVIRONMENT0_HH
#define _BASIC_USAGE_ENVIRONMENT0_HH

#ifndef _BASICUSAGEENVIRONMENT_VERSION_HH
#include "BasicUsageEnvironment_version.hh"
#endif

#ifndef _USAGE_ENVIRONMENT_HH
#include "UsageEnvironment.hh"
#endif

#ifndef _DELAY_QUEUE_HH
#include "DelayQueue.hh"
#endif

#define RESULT_MSG_BUFFER_MAX 1000

// An abstract base class, useful for subclassing
// (e.g., to redefine the implementation of "operator<<")
//这个子类主要就是处理了打印字符信息的方式
class BasicUsageEnvironment0: public UsageEnvironment {
public:
  // redefined virtual functions:
  //返回缓存区字符数据
  virtual MsgString getResultMsg() const;

  virtual void setResultMsg(MsgString msg);
  virtual void setResultMsg(MsgString msg1,
		    MsgString msg2);
  virtual void setResultMsg(MsgString msg1,
		    MsgString msg2,
		    MsgString msg3);
  virtual void setResultErrMsg(MsgString msg, int err = 0);
  //往缓存区后面连接字符，空间不足会截断
  virtual void appendToResultMsg(MsgString msg);
  //往标准出错打印错误信息
  virtual void reportBackgroundError();

protected:
  BasicUsageEnvironment0(TaskScheduler& taskScheduler);
  virtual ~BasicUsageEnvironment0();

private:
  //重置字符缓存区
  void reset();
  //存放字符的缓存区
  char fResultMsgBuffer[RESULT_MSG_BUFFER_MAX];
  //记录fResultMsgBuffer字符个数
  unsigned fCurBufferSize;
  //当前fResultMsgBuffer的最大可用空间
  unsigned fBufferMaxSize;
};

class HandlerSet; // forward

#define MAX_NUM_EVENT_TRIGGERS 32

// An abstract base class, useful for subclassing
// (e.g., to redefine the implementation of socket event handling)

class BasicTaskScheduler0: public TaskScheduler {
public:
  virtual ~BasicTaskScheduler0();
  //让子类实现调用的方法doEventLoop循环调用它，子类把需要处理的监听事件放入这个过程里
  virtual void SingleStep(unsigned maxDelayTime = 0) = 0;
      // "maxDelayTime" is in microseconds.  It allows a subclass to impose a limit
      // on how long "select()" can delay, in case it wants to also do polling.
      // 0 (the default value) means: There's no maximum; just look at the delay queue

public:
  //加入延迟处理事件
  virtual TaskToken scheduleDelayedTask(int64_t microseconds, TaskFunc* proc,
  // Redefined virtual functions:
				void* clientData);
  //从任务延迟队列中删除要处理的事件
  virtual void unscheduleDelayedTask(TaskToken& prevTask);

  virtual void doEventLoop(char* watchVariable);
  //加入一个事件，这里返回的值用来记录事件，这个值是一个mask,只有一位为1，为1位的序号值和其在事件数组fTriggeredEventHandlers里的位置是一样的
  virtual EventTriggerId createEventTrigger(TaskFunc* eventHandlerProc);
  virtual void deleteEventTrigger(EventTriggerId eventTriggerId);
  virtual void triggerEvent(EventTriggerId eventTriggerId, void* clientData = NULL);

protected:
  BasicTaskScheduler0();

protected:
  // To implement delayed operations:
  //延迟操作
  DelayQueue fDelayQueue;

  // To implement background reads:
  //记录文件描述符的链表
  HandlerSet* fHandlers;
  //记录文件描述符的链表个数
  int fLastHandledSocketNum;

  // To implement event triggers:
  //事件触发
  //这里最大只能安排32个事件，正好一个32位的整数，fLastUsedTriggerMask用来也是一个32位的无符号整数，他记录最后一个加到事件的mask.
  EventTriggerId fTriggersAwaitingHandling, fLastUsedTriggerMask; // implemented as 32-bit bitmaps
  //事件调用的过程
  TaskFunc* fTriggeredEventHandlers[MAX_NUM_EVENT_TRIGGERS];
  //事件调用的过程的参数
  void* fTriggeredEventClientDatas[MAX_NUM_EVENT_TRIGGERS];
  //最后被使用的位置（fTriggeredEventHandlers的位置）,
  unsigned fLastUsedTriggerNum; // in the range [0,MAX_NUM_EVENT_TRIGGERS)
};

#endif
